Claude Code Review

Summary

This PR systematically replaces all "vteam" references with "ACP" (Ambient Code Platform) naming across documentation. The changes are comprehensive, covering API groups, namespaces, URLs, container images, and product references. Additionally, 4 new Mermaid architecture diagrams are added to improve documentation clarity.

Scope: 31 files (27 modified, 4 new), 653 additions, 322 deletions
Change Type: Documentation only - no code changes
Risk Level: Low (documentation only, no runtime code affected)

Issues by Severity

🚫 Blocker Issues

None - Documentation-only changes present no blocking issues.

🔴 Critical Issues

None - All changes are cosmetic and do not affect functionality.

🟡 Major Issues

1. Inconsistent References May Remain in Code

Location: Throughout the codebase (not in this PR)

Issue: While this PR updates documentation, the actual runtime code still uses:

• API Group: vteam.ambient-code (should be acp.ambient-code)
• Namespace: vteam-dev (should be acp-dev)
• Image names: vteam_* (should be acp_*)
• Routes: vteam-frontend (should be acp-frontend)

Impact: Documentation now describes a system that doesn't yet exist. Users following the docs will encounter mismatches with actual behavior.

Example from PR:

-apiVersion: vteam.ambient-code/v1alpha1
+apiVersion: acp.ambient-code/v1alpha1

But the actual CRD files in components/manifests/ still use vteam.ambient-code.

Recommendation:

1. Either update this PR to include the actual runtime changes (CRDs, code, manifests), OR
2. Create a tracking issue for the full migration and add a note in CLAUDE.md that docs reflect the target state
3. Consider a phased approach: code changes first, then docs

🔵 Minor Issues

1. CLAUDE.md Still References vteam in Technical Note

Location: CLAUDE.md lines 9-10 (not changed in this PR)

Current State:

> **Note:** This project was formerly known as "vTeam". Technical artifacts (image names, namespaces, API groups) still use "vteam" for backward compatibility.

Issue: This note accurately reflects reality but contradicts the updated docs which show acp everywhere.

Recommendation: Update this note to clarify the migration status:

> **Note:** This project was formerly known as "vTeam". Technical artifacts are being migrated from "vteam" to "acp" naming. Documentation shows the target state; some runtime components may still use legacy "vteam" names during the transition.

2. Missing Verification of Diagram Rendering

Location: New .mmd files

Issue: Mermaid diagrams added without verification that they render correctly in the documentation site (MkDocs).

Files:

• docs/agentic-session-flow.mmd
• docs/component-structure.mmd
• docs/deployment-stack.mmd
• docs/platform-architecture.mmd

Recommendation:

1. Test rendering with mkdocs serve locally
2. Add references to these diagrams in the main docs pages (not just in components/README.md)
3. Consider adding alt text descriptions for accessibility

3. GitLab Integration Docs Heavily Affected

Location: 5 GitLab-related documentation files

Observation: GitLab integration docs were updated extensively (237 lines changed). These docs reference backend endpoints, tokens, and workflows.

Potential Risk: If GitLab integration tests reference the old vteam naming in test scripts or fixtures, they may break.

Recommendation: Cross-reference with:

• e2e/ test fixtures
• CI/CD workflow files
• Any example scripts in scripts/ or examples/

Positive Highlights

✅ Comprehensive Scope

• Thorough: 27 files updated consistently across all documentation categories
• Systematic: API groups, namespaces, URLs, and product names all addressed
• Complete: Both user-facing and developer documentation updated

✅ Improved Documentation Structure

• New Diagrams: 4 Mermaid architecture diagrams add significant visual clarity
• Better Navigation: components/README.md now links to architecture diagrams
• Consistent Terminology: "Ambient Code Platform" used consistently

✅ Maintains Backward Compatibility Notes

• GitLab docs still reference historical context where appropriate
• Upgrade/migration guidance preserved

✅ No Breaking Changes to Code

• Zero risk of runtime breakage since no code files modified
• Safe to merge from a stability perspective

Recommendations

High Priority

1. Clarify Migration Status (Effort: 5 min)

   • Update CLAUDE.md note to reflect transition state
   • Add tracking issue reference if full code migration pending

2. Verify Diagram Rendering (Effort: 10 min)

   • Run mkdocs serve and check all 4 new diagrams render
   • Fix any Mermaid syntax issues

3. Create Follow-up Issue for Code Migration (Effort: 15 min)

   • Document all code locations that need vteam → acp changes:
     • CRD files (components/manifests/base/*-crd.yaml)
     • Go code API group constants
     • Frontend environment variables
     • Container image build scripts
     • Makefile targets
     • CI/CD workflows
   • Link to this PR as the docs baseline

Medium Priority

4. Add Diagram References to Main Docs (Effort: 10 min)

   • Link diagrams from docs/index.md or architecture sections
   • Don't bury them only in components/README.md

5. Audit Test Fixtures (Effort: 15 min)

   • Check e2e/ for hardcoded vteam references
   • Update test expectations to match new docs

Low Priority

6. Add Accessibility Alt Text (Effort: 10 min)
   • Consider adding descriptions for screen readers to diagram pages

Approval Status

✅ Approved with Recommendations

This PR is safe to merge as-is since it only affects documentation. However, I strongly recommend addressing the "Clarify Migration Status" item (#1) before merge to avoid user confusion.

The code migration should be tracked separately and completed soon after this merges to avoid documentation drift.

Testing Checklist

Before merge:

• Run mkdocs serve and verify all 4 new diagrams render correctly
• Spot-check 2-3 updated doc pages in browser
• Verify components/README.md diagram links work
• Update CLAUDE.md migration status note (or create follow-up issue)
• Create tracking issue for code migration (or confirm one exists)

References

• Documentation Standards: CLAUDE.md lines 1069-1075
• Related Work: This PR should be paired with code changes to CRDs, manifests, and Go constants
• Backward Compatibility Note: CLAUDE.md lines 9-10

🔍 View AI decision process (logs available for 90 days)